A-XAPP SDK 基本配置

一、XAPP SDK 基本配置

程序运行前要配置 XAPP SDK config 配置信息，之后调用XLinkSDK.start()后生效。前面快速开始时已经介绍了最简单的配置方式，此部分将具体地介绍一些常用的配置。

XAPP SDK 支持以下功能配置：

• 调试日志输出功能
• API 域名配置（API 环境切换）
• CM服务器连接版本（自v6.2.6.x版本起）
• 全局的数据通讯策略
• 全局的回调监听

XLinkConfig.Builder builder = new XLinkConfig.Builder()
        //设置输出日志配置信息
        .setLogConfig(XLinkAndroidSDK.defaultLogConfig(context))
        //设置API服务器地址与端口,默认值为正式环境: https://api2.xlink.cn,443
        .setApiServer(hostApi, portApi)
        //设置CM服务器地址与端口,默认值为正式环境: mqtt.xlink.cn,1884
        .setCloudServer(hostCM, portCM)；
        //SSL目前仅对CM连接有效,测试环境时需要开启SSL false
        .setEnableSSL(ssl)
        //设置数据默认发送策略
        .setSendDataPolicy(sendPolicy)
        //是否打印部分日志
        .setDebug(true)
        //设置云端回调监听
        .setXLinkCloudListener(xlinkListener)
        //设置用户登录回调监听
        .setUserListener(xlinkListener)
        //设置数据回调监听
        .setDataListener(xlinkListener)
        //设置物模型回调监听
        .setTMLAttributeListener(xlinkListener)
        //设置设备状态监听
        .setDeviceStateListener(xlinkListener);

1、 调试日志输出功能

XAPP SDK 的日志输出功能必须设置才能正常使用，否则无法正常输出到控制台查看，XAPP SDK 已提供了默认的日志输出实现，默认日志配置如下：

• 将输出日志到控制台
• 将日志信息保存到日志文件中
• 日志文件保存默认位置：**/sdcard/xlink/包名_log_时间.txt**

注意事项：自v6.2.6.x版本起，默认情况下日志文件保存的位置为 /sdcard/xlink/包名/log_时间.txt

默认的日志输出配置仅需要一句代码，若无法正常输出日志，请确认是否开启了存储权限，若有其它问题可参考 FAQ

XLinkConfig config = new XLinkConfig.Builder()
        ...
        .setLogConfig(XLinkAndroidSDK.defaultLogConfig(context))
        ...

注意事项：日志配置允许进行自定义配置，默认配置可以满足大部分情况下的要求，如果需要更改日志文件保存路径或者是自定义配置信息，请查看进阶使用说明。

2、API域名配置

API 域名默认是使用正式环境的 API 域名配置，配置选项列表说明如下：

配置名称	含义	默认值
setCloudServer(String, int)	设置 CM 服务器	mqtt.xlink.cn,1884
setApiServer(String, int)	设置 HTTP API 服务器	https://api2.xlink.cn, 443
setEnableSSL(Boolean)	是否使用 SSL	true

其中关于 API 及 CM 服务器是包括了 XLink 正式环境与测试环境的地址，当然也允许配置成私有云地址；以下为不同环境下的地址信息:

环境	域名	端口	启用SSL(仅公有云)
XLink 公有云正式环境 API	https://api2.xlink.cn	443
XLink 公有云正式环境 CM	mqtt.xlink.cn	1884	true
XLink 公有云正式环境 CM	mqtt.xlink.cn	1883	false（无SSL）
XLink 公有云测试环境 API	http://dev-api.xlink.cn	80
XLink 公有云测试环境 CM	dev-cm.xlink.cn	1884	true
XLink 公有云测试环境 CM	dev-cm.xlink.cn	1883	false（无SSL）

注意：

1. 不进行服务器地址配置的情况下，默认使用正式环境信息
2. 公有云同时支持 SSL 端口及非 SSL 端口，默认情况下使用 SSL 端口，建议使用此端口；确认不需要进行启用 SSL 时可使用1883端口

3、 CM服务器连接版本（自v6.2.x版本起）

由于v6.2版本的功能更新（详情请查看版本升级 md)中v6.2相关升级说明），CM 服务器版本也同步更新。
目前公有云已更新到版本3，部分企业环境的 CM 服务器版本可能未进行更新，依然需要使用旧版本连接。

自v6.2版本以后 XAPP SDK 默认使用版本3进行 CM 服务器的连接，可通过以下配置变更连接版本。

XLinkConfig.Builder builder = XLinkConfig.newBuilder()
        //默认使用版本为3，可切换为2版本
        .setMQTTClientVersion(2)
        ...
        .build

注意事项：CM 服务器版本并不是高版本必然优于低版本，主要的版本变更是由于新功能的支持，所有原有功能和基础功能都是正常可用的，当不需要使用提供的新功能不需要升级。

4、全局的数据通讯策略

物联云平台采用数据端点来描述物理设备的状态和能力

• 可通过设备状况的查询和回调接口来获取设备的实时状态
• 可通过更新数据端点状态的接口来实现设备的远程控制

XAPP SDK 与设备连接有不同的情况，包括以下三种情况：

• 通过云平台与设备连接，后续简称为：云端连接
• 通过内网（局域网）与设备连接，后续简称为：内网连接
• 同时存在云端连接与内网连接

XAPP SDK 支持指定内网的局域网连接或外网的云端连接来发送数据，也可以采用 AUTO 模式由 XAPP SDK 底层自适应内外的数据通讯。数据发送的策略有如下几种：

发送策略	说明
AUTO	默认值，自动选择发送数据的通道(内/外网)，选择的依据是当前通道的 RTT，RTT 低的通道会被选中
LOCAL_ONLY	只尝试从内网发送
LOCAL_FIRST	尝试从内网发送，失败则尝试外网发送
CLOUD_ONLY	只尝试从外网发送
CLOUD_FIRST	尝试从外网发送，失败则尝试内网发送

在初始化 XAPP SDK 时可以设置全局使用的数据通讯策略：

XLinkConfig config = new XLinkConfig.Builder()
        ...
        .setSendDataPolicy(XLinkSendDataPolicy.CLOUD_ONLY)
        ...

5、全局的回调监听

XAPP SDK 提供了常用接口的全局回调，包括了以下几种回调

• XLinkCloudListener-云端回调，XAPP SDK 与云平台连接的状态回调及所有来自云端的消息推送
• XLinkUserListener-用户状态回调，XAPP SDK 维护的用户状态回调，涉及用户退出、授权信息过期、踢出等状态
• XLinkDataListener-数据回调，XAPP SDK 接收到数据端点变更的通知回调
• XLinkDeviceStateListener-设备状态回调，XAPP SDK 维护的设备状态变更时的通知回调
• XLinkDeviceEventListener-设备事件通知回调，XAPP SDK 维护的设备发送事件到 XAPP SDK 时的通知回调

这部分的监听回调都在全局配置时添加的，一般情况下是在应用对象中（Application）中统一进行监听和处理

5.1、XLinkCloudListener-云端回调

云端回调包括 XAPP SDK 连接到 CM 云端服务器的连接状态回调,以及所有来自云端的消息推送

// 云端回调
configBuilder.setCloudListener(new XLinkCloudListener() {
    @override
    public void onCloudStateChanged(CloudConnectionState state) {
        // 当SDK与云平台连上/断开的时候，会回调这个方法
        // 根据 state 状态可判断连接状态为断开/连接中/已连接
    }
 
    @Override
    public void onEventNotify(EventNotify eventNotify) {
        // 当SDK连接上云端，并接收到云端推送时，会回调这个方法。
    }
});

事件的详细介绍说明请查看进阶篇-云端消息推送

5.2、XLinkUserListener-用户状态回调

用户登录状态的回调，在用户账号退出时，会通过此回调进行用户退出账号原因的通知

//用户信息回调
configBuilder.setUserListener(new XLinkUserListener() {
    @Override
    public void onUserLogout(LogoutReason reason) {
        // 用户被下线（被踢或者手动退出）/授权信息过期 的时候，会回调这个方法。
        // 请根据LogoutReason进行处理
    }
});

用户退出原因有三种：

原因	说明
USER_LOGOUT	用户主动退出，一般情况下由于调用XLinkSDK.logoutAndStop()引起的
SINGLE_SIGN_KICK_OFF	用户账号由于被其它人登录导致了当前账号被踢出的
TOKEN_EXPIRED	用户凭证过期

通常情况下，SINGLE_SIGN_KICK_OFF与TOKEN_EXPIRED都是需要用户重新登录的，一般发生时也建议调用XLinkSDK.logoutAndStop()停止当前 XAPP SDK

用户退出原因及授权信息处理详细说明请查看进阶篇-用户授权管理

5.3、XLinkDataListener-数据回调

数据回调时目前最主要的是数据端点的变更通知回调。设备的数据端点变更时，当设备进行上报后会通过回调通知到 APP 数据端点的更新。

// 数据回调
configBuilder.setDataListener(new XLinkDataListener() {
    @Override
    public void onDataPointUpdate(XDevice xDevice, List<XLinkDataPoint> list) {
        // 当SDK收到设备上报的数据端点时，会回调这个方法。
    }
});

数据端点相关说明请查看进阶篇-数据端点详解

5.4、XLinkDeviceStateListener-设备状态回调

设备状态回调在设备状态发生变更时会进行回调，请注意并非所有的设备都会在此回调接口中进行回调，有且仅有存在设备维护列表中的设备状态发生改变时才会通知此回调通知，关于“维护列表设备”的详细说明可参考 进阶篇-设备连接状态管理

设备状态回调的注意点：

1. 通过XLinkSyncDeviceListTask同步列表操作任务进行设备同步后，默认都会添加到维护列表中
2. 通过XLinkAddDeviceTask添加设备任务添加的设备也会添加到设备维护列表中
3. 通过XLinkSyncHomeDeviceListTask同步Home中设备列表任务进行设备同步后，默认都会添加到维护列表中

// 设备状态回调
configBuilder.setDeviceStateListener(new XLinkDeviceStateListener() {
    @Override
    public void onDeviceStateChanged(XDevice xDevice, XDevice.State state) {
        // 受SDK管理的设备状态发生改变时,一般情况下同步下来已订阅过的设备都会在维护列表中
    }
     
    @Override
    public void onDeviceChanged(XDevice xDevice, XDevice.Event event){
        // 设备属性或者设备状态发生改变时，会回调这个方法。
        // 详情请参阅XDevice.Event
    }
});

5.5、 XLinkDeviceEventListener-设备事件通知回调（自v6.2.x版本起）

当设备发送事件给 XAPP SDK 时，XAPP SDK 接收到事件后将会通过此回调通知用户。请参考 API-XLinkDeviceEvent

configBuilder.setEventListener(new XLinkDeviceEventListener(){
        @Override
        public void onDeviceEventNotify(@NotNull XDevice device, @NotNull List<XLinkDeviceEvent> event, int from) {
            //接收到来自设备的事件时将会回调此方法，from为事件来自内网或者是云端的标识
        }
})

• from

值	说明
XLinkConstant.FROM_LOCAL	来自内网事件
XLinkConstant.FROM_CLOUD	来自云端事件

6、 XAPP SDK 启动与停止

注意以上为 XAPP SDK 初始化的一些基础配置，XAPP SDK 需要在启动后才能正常使用

// 启动SDK
XLinkSDK.start();
不使用SDK时，可调用stop()。
 
// 停止SDK, 断开云端连接，回收资源
XLinkSDK.stop();
 
当App退出登录（授权失败或其他原因需要重新授权的情况）时，可调用XLinkSDK.logoutAndStop()
 
 
// 停止SDK, 断开云端连接，回收资源，清除授权信息。
//请注意此处会停止当前的SDK,如果需要再次使用必须再次start SDK
XLinkSDK.logoutAndStop();

注：

1. 任何时候使用XLinkSDK.stop()方法都会导致 XAPP SDK 的中止，而一旦 XAPP SDK 中止后，就不会再与设备保持任何通讯
2. 在任何一次XLinkSDK.stop() 之后需要使用 XAPP SDK 的话，请务必调用 XLinkSDK.start() 操作

二、更新说明

日期	更新内容
2019-04-03	自v6.2.6.x版本起更新默认的日志文件保存位置
2019-01-15	自v6.2.6.x版本起 新增连接CM服务端的版本号配置 新增设备事件回调说明

上次更新：2024-05-09